home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / doc / extra.doc < prev    next >
Text File  |  1993-07-05  |  13KB  |  541 lines
  1.  
  2.     EXTRA.DOC (c)Copyright 1990, Matthew Dillon, All Rights Reserved
  3.  
  4. TABLE OF CONTENTS
  5.  
  6. c.lib/extra/expand_args
  7. c.lib/extra/getfnl
  8. c.lib/extra/GetHead
  9. c.lib/extra/GetPred
  10. c.lib/extra/GetSucc
  11. c.lib/extra/GetTail
  12. c.lib/extra/LockAddr
  13. c.lib/extra/LockAddrB
  14. c.lib/extra/TryLockAddr
  15. c.lib/extra/TryLockAddrB
  16. c.lib/extra/UnlockAddr
  17. c.lib/extra/UnlockAddrB
  18. c.lib/extra/MulDiv
  19. c.lib/extra/MulDivU
  20. c.lib/extra/OS2_0
  21. c.lib/extra/AutoAllocMiscResource
  22. c.lib/extra/AutoFreeMiscResource
  23. c.lib/extra/SetFileDate
  24. c.lib/extra/sleep
  25. c.lib/extra/strupper
  26. c.lib/extra/wildcard
  27. c.lib/extra/fhprintf
  28.  
  29.  
  30. extra/expand_args                    extra/expand_args
  31.  
  32.    NAME
  33.     expand_args   - expand command line argument wildcards
  34.  
  35.    SYNOPSIS
  36.     int error = expand_args(xac, xav, &ac, &av);
  37.     int xac;
  38.     const char **xav;
  39.     int ac;
  40.     char **av;
  41.  
  42.    FUNCTION
  43.     expand_args() takes an argc/argv list and expands any wildcard
  44.     arguments by scanning the appropriate directory.  expand_args()
  45.     malloc()s however much memory it needs to create the new list and
  46.     ignores xav[0] (i.e. just copies it to the returned av[0] without
  47.     doing a wildcard expansion).
  48.  
  49.     expand_args() fills in the ac and av variables with its own
  50.     malloc()d version of the argument list, now completely expanded.
  51.     There is no limit to the number of files that may be in this
  52.     result list (you could conceivably have THOUSANDS).
  53.  
  54.     expand_args() may be used to expand arbitrary AmigaDOS wildcards
  55.     and is not limited to an anchored search.  For example, you could
  56.     specify:
  57.  
  58.         sys:#?/#?
  59.  
  60.     In which case a list of a second level files/dirs will be generated.
  61.     expand_args in the above case scans sys: then scans any sub directories
  62.     found in sys:
  63.  
  64.     Generic AmigaDOS wildcarding is used and incredibly complex wildcards
  65.     may be specified.  However, please note that any wildcard elements
  66.     containing #? in combination with other elements (such as (a|b|c))
  67.     will cause HUGE amounts of stack to be used and also quite a bit
  68.     of memory during the scan.  expand_args() limits itself to 4K
  69.     of stack before giving up.
  70.  
  71.     Any program that uses expand_args() should be run with at least
  72.     8K of stack.
  73.  
  74.    EXAMPLE
  75.     #include <stdio.h>
  76.  
  77.     main(xac, xav)
  78.     int xac;
  79.     char **xav;
  80.     {
  81.         int ac;
  82.         char **av;
  83.         short i;
  84.  
  85.         int error = expand_args(xac, xav, &ac, &av);
  86.         for (i = 1; i < ac; ++i) {
  87.         printf("%s\n", av[i]);
  88.         }
  89.     }
  90.  
  91.    INPUTS
  92.     int xac;        original argc
  93.     char **xav;        original argv
  94.     int *ac;        pointer to new argc
  95.     char ***av;        pointer to new argv
  96.  
  97.    RESULTS
  98.     int error;        0 if all went well, non-zero otherwise
  99.  
  100.    SEE ALSO
  101.  
  102.  
  103.  
  104. extra/getfnl                        extra/getfnl
  105.  
  106.    NAME
  107.     getfnl - get file name list.  Scan a directory and return list of
  108.          files that match the optional wildcard
  109.  
  110.     This is a non-standard function and exists for compatibility with
  111.     other commercial compilers.
  112.  
  113.    SYNOPSIS
  114.     int n = getfnl(pat, buf, bufsize, attr);
  115.     const char *pat;
  116.     char *buf;
  117.     int bufsize;
  118.     int attr;
  119.  
  120.    FUNCTION
  121.     getfnl() scans the specified anchored AmigaDOS pattern and fills
  122.     the specified buffer (up to bufsize bytes) with file names
  123.     separated by a nul character (\0), ending the list with a double
  124.     nul (\0\0).  getfnl() returns the number of files/dirs in the buffer
  125.     or -1 if there was not enough room
  126.  
  127.     The pattern pat is an AmigaDOS pattern such as "df0:#?.c".  buf
  128.     is a buffer of bufsize bytes.  attr determines what kinds of
  129.     files are valid:
  130.  
  131.         0    normal files only
  132.         1    files and directories
  133.  
  134.    NOTE
  135.     getfnl() exists for compatibility, but expand_args() is a much
  136.     better function to use if you want a list of files & dirs.
  137.  
  138.    EXAMPLE
  139.     #include <stdio.h>
  140.  
  141.     char Buf[4096];
  142.  
  143.     main(ac, av)
  144.     int ac;
  145.     char *av[];
  146.     {
  147.         int n;
  148.  
  149.         if (ac != 2) {
  150.         puts("Expected an anchored wildcard such as '#?'");
  151.         exit(1);
  152.         }
  153.         n = getfnl(av[1], Buf, sizeof(Buf), 1);
  154.         {
  155.         char *ptr = Buf;
  156.         while (*ptr) {              /*  look for \0\0   */
  157.             puts(ptr);
  158.             ptr += strlen(ptr) + 1; /*  skip first \0   */
  159.         }
  160.         }
  161.         return(0);
  162.     }
  163.  
  164.  
  165.    INPUTS
  166.     const char *pat;    pattern to scan for (anchored)
  167.     char *buf;        buffer to put results in
  168.     int bufsize;        size of buffer
  169.     int attr;        attribes (0 or 1)
  170.  
  171.    RESULTS
  172.     int n;            number of file names in buffer or -1 on error
  173.  
  174.    SEE ALSO
  175.     strbpl, wildcard
  176.  
  177.  
  178.  
  179. extra/GetHead                        extra/GetHead
  180. extra/GetTail                        extra/GetTail
  181. extra/GetSucc                        extra/GetSucc
  182. extra/GetPred                        extra/GetPred
  183.  
  184.    NAME
  185.     GetHead     -    get first element in EXEC list
  186.     GetTail     -    get last element in EXEC list
  187.     GetSucc     -    get next element after some element (node)
  188.     GetPred     -    get previous element before some element (node)
  189.  
  190.    SYNOPSIS
  191.     struct Node *node = GetHead(list);
  192.     struct Node *node = GetTail(list);
  193.     struct Node *node = GetSucc(oldNode);
  194.     struct Node *node = GetPred(oldNode);
  195.  
  196.     const struct Node *oldNode;
  197.     const struct List *list;
  198.  
  199.    FUNCTION
  200.     These functions allow scannig of EXEC style lists (which are also
  201.     useful for many programs having nothing to do with EXEC)
  202.  
  203.     GetHead() returns the first node in a list or NULL if the list is
  204.           empty
  205.  
  206.     GetTail() returns the last node in a list or NULL if the list is
  207.           empty
  208.  
  209.     GetSucc() returns the next node in a list (given some intermediate
  210.           node) or NULL when we reach the end of the list
  211.  
  212.     GetPred() returns the previous node in a list before some intermediate
  213.           node or NULL when we reach the beginning of the list
  214.  
  215.    NOTE
  216.     These are DICE functions and do not exist outside of DICE, though
  217.     easily written.
  218.  
  219.    EXAMPLE
  220.     /*
  221.      *  Stupid symbol create/delete/list program.  Note that for a real
  222.      *  symbol table you want to use hash tables.
  223.      */
  224.  
  225.     #include <lists.h>    /*  non-standard header file    */
  226.     #include <stdio.h>
  227.     #include <stdlib.h>
  228.     #include <string.h>
  229.  
  230.     typedef struct List List;
  231.     typedef struct Node Node;
  232.  
  233.     List    SymList;
  234.  
  235.     void AddSymbol(char *);
  236.     void DelSymbol(char *);
  237.     Node *FindSymbol(char *);
  238.  
  239.     main()
  240.     {
  241.         char buf[256];
  242.         char symBuf[256];
  243.         short notDone = 1;
  244.  
  245.         NewList(&SymList);
  246.  
  247.         puts("(return for help)");
  248.  
  249.         while (notDone) {
  250.         printf("Enter Command: ");
  251.         fflush(stdout);
  252.         if (gets(buf) == NULL)
  253.             break;
  254.         switch(buf[0]) {
  255.         case 'a':
  256.             if (sscanf(buf + 1, "%s", symBuf) == 1)
  257.             AddSymbol(symBuf);
  258.             break;
  259.         case 'd':
  260.             if (sscanf(buf + 1, "%s", symBuf) == 1)
  261.             DelSymbol(symBuf);
  262.             break;
  263.         case 'l':
  264.             {
  265.             Node *node;
  266.             for (node = GetHead(&SymList); node; node = GetSucc(node))
  267.                 puts(node->ln_Name);
  268.             }
  269.             break;
  270.         case 'q':
  271.             notDone = 0;
  272.             break;
  273.         default:
  274.             puts("<return>      -help   ");
  275.             puts("a name        -add symbol");
  276.             puts("d name        -delete symbol");
  277.             puts("l             -list symbols");
  278.             puts("q             -quit");
  279.             break;
  280.         }
  281.         }
  282.         puts("bye!");
  283.         return(0);
  284.     }
  285.  
  286.     void
  287.     AddSymbol(name)
  288.     char *name;
  289.     {
  290.         Node *node;
  291.         if (FindSymbol(name)) {
  292.         puts("already exists!");
  293.         exit(1);
  294.         }
  295.         if (node = malloc(sizeof(Node))) {
  296.         AddTail(&SymList, node);
  297.         node->ln_Name = strdup(name);   /* bad code, not checking */
  298.                         /* for error result!      */
  299.         }
  300.     }
  301.  
  302.     void
  303.     DelSymbol(name)
  304.     char *name;
  305.     {
  306.         Node *node;
  307.  
  308.         if (node = FindSymbol(name)) {
  309.         Remove(node);           /*  take out of list    */
  310.         free(node->ln_Name);    /*  free name           */
  311.         free(node);             /*  free node last      */
  312.         puts("ok");
  313.         } else {
  314.         puts("Couldn't find it!");
  315.         }
  316.     }
  317.  
  318.     Node *
  319.     FindSymbol(name)
  320.     char *name;
  321.     {
  322.         Node *node;
  323.         for (node = GetHead(&SymList); node; node = GetSucc(node)) {
  324.         if (strcmp(node->ln_Name, name) == 0)
  325.             return(node);
  326.         }
  327.         return(NULL);
  328.     }
  329.  
  330.  
  331.    INPUTS
  332.     struct List *list;    list to get head or tail node from
  333.  
  334.     struct Node *oldNode;    node from which to get relative successor or
  335.                 predecessor from
  336.  
  337.    RESULTS
  338.     struct Node *node;    returned node or NULL
  339.  
  340.    SEE ALSO
  341.  
  342.  
  343. c.lib/extra/LockAddr
  344. c.lib/extra/LockAddrB
  345. c.lib/extra/TryLockAddr
  346. c.lib/extra/TryLockAddrB
  347. c.lib/extra/UnlockAddr
  348. c.lib/extra/UnlockAddrB
  349.  
  350.  
  351. extra/LockAddr                        extra/LockAddr
  352. extra/LockAddrB                     extra/LockAddrB
  353. extra/TryLockAddr                    extra/TryLockAddr
  354. extra/TryLockAddrB                    extra/TryLockAddrB
  355. extra/UnlockAddr                    extra/UnlockAddr
  356. extra/UnlockAddrB                    extra/UnlockAddrB
  357.  
  358.    NAME
  359.     LockAddr    -   Gain Exclusive, Fast semaphore (bit 0)
  360.     LockAddrB    -   Gain Exclusive, Fast semaphore (bit n 0-7)
  361.     TryLockAddr    -   Non-Blocking version of LockAddr
  362.     TryLockAddrB    -   Non-Blocking version of LockAddrB
  363.     UnlockAddr    -   Release exclusive semaphore, bit 0
  364.     UnlockAddrB    -   Release exclusive semaphore, bit n 0-7
  365.  
  366.    SYNOPSIS
  367.     void LockAddr(lck);
  368.     void LockAddrB(bitno, lck);
  369.     int r = TryLockAddr(lck);
  370.     int r = TryLockAddrB(bitno, lck);
  371.  
  372.     void UnlockAddr(lck);
  373.     void UnlockAddrB(bitno, lck);
  374.  
  375.     long lck[2];
  376.  
  377.    FUNCTION
  378.     These are custom DICE functions used for inter-task locking semaphores
  379.     in programs that need such functions.  These routines are somewhat
  380.     faster than standard Amiga semaphore routines and take less memory,
  381.     though at the cost of DICE specific.
  382.  
  383.     To use an inter-task lock one first initializes an lck array to
  384.     0's.  long lck[2]; is an array of two longwords that the lock
  385.     routines will use to perform their stuff.  This array should be
  386.     zero'd only once at program initialization time (the master task
  387.     before any other tasks are created that use it).
  388.  
  389.     Each lck array may hold up to 8 locks, hence the LockAddrB() calls.
  390.     The non-B calls use lock #0 for simplicity.  For simplicity we
  391.     will only discuss non-B calls.    To gain a lock you may call
  392.     LockAddr() with the address of the lck array (which, being an array,
  393.     does not need the & in the call).  This routine will not return
  394.     until the lock can be obtained.
  395.  
  396.     You may also use TryLockAddr() to attempt to gain a lock.  The
  397.     return value is:
  398.  
  399.         -1        Unable to obtain the lock, it is in use
  400.         1        Lock obtained
  401.  
  402.     To release an obtained lock you call UnlockAddr(lck).  DO NOT RELEASE
  403.     A LOCK YOU DO NOT HAVE!
  404.  
  405.    EXAMPLE
  406.     /*
  407.      *  This program obtains a lock based at a public message port and
  408.      *  holds it for ten seconds before releasing it.  The public message
  409.      *  port is left in memory (but only exists once no matter how many
  410.      *  programs you run).
  411.      *
  412.      *  To test locking, open up two or more CLI's and run the program
  413.      *  simultaniously (or as close as your fingers can make it) two or
  414.      *  more times.  Only one program will 'have' the lock at a time.
  415.      *
  416.      *  we use AllocMem() so the port survives the program
  417.      */
  418.  
  419.     #include <exec/types.h>
  420.     #include <exec/ports.h>
  421.     #include <exec/memory.h>
  422.     #include <stdio.h>
  423.     #include <stdlib.h>
  424.     #include <assert.h>
  425.  
  426.     typedef struct {
  427.         struct MsgPort Port;
  428.         long       Lock[2];
  429.     } MyPort;
  430.  
  431.     extern void *FindPort();
  432.     extern void *CreatePort();
  433.     extern void *AllocMem();
  434.  
  435.     MyPort *Port;
  436.     short HaveLock;
  437.  
  438.     int
  439.     brk()
  440.     {
  441.         if (HaveLock)
  442.         UnlockAddr(Port->Lock);
  443.         return(1);      /*  abort   */
  444.     }
  445.  
  446.     main()
  447.     {
  448.         char *portName = "Lock-Test";
  449.  
  450.         onbreak(brk);
  451.  
  452.         Forbid();
  453.         if ((Port = FindPort(portName)) == NULL) {
  454.         MyPort *port;
  455.         port = AllocMem(sizeof(MyPort) + strlen(portName) + 1, MEMF_PUBLIC | MEMF_CLEAR);
  456.         assert(port);
  457.  
  458.         port->Port.mp_Node.ln_Name = (char *)(port + 1);
  459.         port->Port.mp_Node.ln_Type = NT_MSGPORT;
  460.         strcpy(port->Port.mp_Node.ln_Name, portName);
  461.         AddPort(port);
  462.  
  463.         Port = port;
  464.         }
  465.         Permit();
  466.  
  467.         puts("getting lock");
  468.         LockAddr(Port->Lock);
  469.         HaveLock = 1;
  470.         puts("Got the lock!, sleeping for 10 seconds");
  471.         sleep(10);
  472.         UnlockAddr(Port->Lock);
  473.         HaveLock = 0;
  474.         puts("released lock");
  475.         return(0);
  476.     }
  477.  
  478.    INPUTS
  479.     long *lck;        A pointer to two longwords, initially zero'd
  480.  
  481.     int bitno;        lock # ... up to 8 independant locks exist for
  482.                 each lck structure
  483.  
  484.    RESULTS
  485.     int r;            (TryLock only), -1 on failure, 1 on success.
  486.  
  487.    SEE ALSO
  488.  
  489.  
  490. extra/fhprintf                        extra/fhprintf
  491.  
  492.    NAME
  493.     fhprintf - formatted printing to a DOS file handle
  494.  
  495.    SYNOPSIS
  496.     int n = fhprintf(fh, ctl, ...);
  497.     BPTR fh;
  498.     const char *ctl;
  499.  
  500.    FUNCTION
  501.     fhprintf() provides a method of using DICE's pfmt lib to do
  502.     formatted printing to a file handle instead of a stdio file
  503.     pointer.  Output is unbuffered and thus not very efficient,
  504.     but the call can be extremely useful when debugging libraries
  505.     and such.
  506.  
  507.    EXAMPLE
  508.  
  509.     void
  510.     _main(ac, av)
  511.     int ac;
  512.     char *av[];
  513.     {
  514.         fhprintf(Output(), "hello world %d!\n", 23);
  515.     }
  516.  
  517.    INPUTS
  518.     BPTR fh;        DOS file handle
  519.     const char *ctl;    format string, see printf()
  520.  
  521.    RESULTS
  522.     int n;            number of characters output
  523.  
  524.    SEE ALSO
  525.     printf, sprintf, vsprintf, fprintf, vfprintf
  526.  
  527.  
  528.  
  529. extra/MulDiv                        extra/MulDiv
  530. extra/MulDivU                        extra/MulDivU
  531. extra/OS2_0                        extra/OS2_0
  532. extra/AutoAllocMiscResource                extra/AutoAllocMiscResource
  533. extra/AutoFreeMiscResource                extra/AutoFreeMiscResource
  534. extra/SetFileDate                    extra/SetFileDate
  535. extra/strupper                        extra/strupper
  536. extra/wildcard                        extra/wildcard
  537.  
  538.     These manual pages have not been written yet, sorry!
  539.  
  540.  
  541.